home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Borland / Borland C++ V5.02 / OWLINC.PAK / TOOLTIP.H < prev    next >
C/C++ Source or Header  |  1997-05-06  |  16KB  |  481 lines
  1. //----------------------------------------------------------------------------
  2. // ObjectWindows
  3. // Copyright (c) 1995, 1997 by Borland International, All Rights Reserved
  4. //
  5. //$Revision:   10.22  $
  6. //
  7. // Definition of the TTooltip class and helper objects
  8. //----------------------------------------------------------------------------
  9. #if !defined(OWL_TOOLTIP_H)
  10. #define OWL_TOOLTIP_H
  11.  
  12. #if !defined(OWL_COMMCTRL_H)
  13. # include <owl/commctrl.h>
  14. #endif
  15. #if !defined(OWL_CONTAIN_H)
  16. # include <owl/contain.h>
  17. #endif
  18.  
  19. #if defined(BI_NAMESPACE)
  20. namespace OWL {
  21. #endif
  22.  
  23. // Generic definitions/compiler options (eg. alignment) preceeding the 
  24. // definition of classes
  25. #include <services/preclass.h>
  26.  
  27. class _OWLCLASS TFont;
  28. class _OWLCLASS TTooltip;
  29.  
  30. //
  31. // class TToolInfo
  32. // ~~~~~ ~~~~~~~~~
  33. // TToolInfo contains information about a particular tool (a tool is
  34. // either a window or an application-defined rectangular area within
  35. // a window's client area). For example, it contains the text
  36. // to be displayed in the tooltip window.
  37. //
  38. class _OWLCLASS TToolInfo : public TOOLINFO {
  39.   public:
  40.  
  41.     // Default constructor of TToolInfo
  42.     //
  43.     TToolInfo(bool allocCache = false);
  44.  
  45.     // Constructor for a tooltip associated with a rectangular area
  46.     // within a window's client area. The 'window' receives
  47.     // 'TTN_NEEDTEXT' notifications if 'txt' is not provided.
  48.     //
  49.     TToolInfo(HWND window, const TRect& rect, uint toolId,
  50.               const char* txt = LPSTR_TEXTCALLBACK);
  51.  
  52.     // Constructor for a tooltip associated with a rectangular area
  53.     // within a window's client area. The 'txtRes' specifies the ID
  54.     // of the string to be used by the tooltip window.
  55.     //
  56.     TToolInfo(HWND window, const TRect&, uint toolId,
  57.               int resId,  HINSTANCE txtResModule);
  58.  
  59.     // Constructor for tool implemented as windows (eg. child/controls).
  60.     // 'parent' receives the 'TTN_NEEDTEXT' notification in case where
  61.     // the default LPSTR_TEXTCALLBACK is used for the 'txt' parameter.
  62.     //
  63.     TToolInfo(HWND parent, HWND toolHwnd,
  64.               const char* txt = LPSTR_TEXTCALLBACK);
  65.  
  66.     // Constructor for tool implemented as windows (eg. child/controls).
  67.     // 'resId' identifies the resource ID of the string to be used by
  68.     // the tooltip window.
  69.     //
  70.     TToolInfo(HWND parent, HWND toolHwnd, int resId, HINSTANCE strResModule);
  71.  
  72.     // Set data members of the TOOLINFO structure which identify each tool
  73.     //
  74.     void        SetToolInfo(HWND toolWin, uint id, const TRect& rc);
  75.     void        SetToolInfo(HWND toolWin, uint id);
  76.     void        SetToolInfo(HWND toolWin, HWND parent);
  77.  
  78.     // Set the text associated with a tooltip and the tool rectangles
  79.     //
  80.     void        SetText(int resId, HINSTANCE hinstance);
  81.     void        SetText(const char far* text, bool copy = true);
  82.     void        SetRect(const TRect& rect);
  83.  
  84.     // Helper routine which returns the 'HWND'/rect associated with a
  85.     // particular tool.
  86.     //
  87.     HWND        GetToolWindow() const;
  88.     void        GetToolRect(TRect& rect) const;
  89.  
  90.     // Helper routine to help determine whether a particular
  91.     // location is pertinent to a tool
  92.     //
  93.     bool        IsPointInTool(HWND win, const TPoint& pt) const;
  94.  
  95.     // Copy ctr & assignment operator
  96.     //
  97.     TToolInfo(const TToolInfo&);
  98.     TToolInfo& operator =(const TToolInfo&);
  99.  
  100.     // Checks whether two TToolInfo structures refer to the same tool
  101.     //
  102.     bool    operator==(const TToolInfo& ti) const;
  103.  
  104.     // Return/clear cached text
  105.     //
  106.     const char* GetCacheText() const;
  107.     void        FlushCacheText();
  108.  
  109.   private:
  110.     TAPointer<char> CacheText;
  111. };
  112.  
  113. //
  114. // class TTooltipHitTestInfo
  115. // ~~~~~ ~~~~~~~~~~~~~~~~~~~
  116. // TTooltipHitTestInfo is a thin [very thin] wrapper around
  117. // the TTHITTESTINFO structure, used to determined whether a
  118. // point is within the bounding rectangle of a particular tool.
  119. // It's a place-holder for future ObjectWindows enhancements to
  120. // tooltip hit-testing.
  121. //
  122. class _OWLCLASS TTooltipHitTestInfo : public TTHITTESTINFO {
  123. };
  124.  
  125. //
  126. // class TTooltipEnabler
  127. // ~~~~~ ~~~~~~~~~~~~~~~
  128. // TTooltipEnabler is the object forwarded along the command-chain to
  129. // retrieve the tip text of a tool. The object is not a 'true' command 
  130. // enabler [i.e. invoking SetCheck or Enable do not modify the state of the
  131. // command associated with the tool]; however, by using the 'CommandEnabler'
  132. // setup retrieving the text of tools, the potential of the commands are
  133. // given first crack at customizing the text.
  134. //
  135. class _OWLCLASS TTooltipEnabler : public TCommandEnabler {
  136.   public:
  137.     TTooltipEnabler(TTooltipText& tt, TWindow::THandle hReceiver);
  138.  
  139.     // Override member functions of TCommandEnabler
  140.     //
  141.     void  SetText(const char far* text);
  142.     void  SetCheck(int /*check*/);
  143.  
  144.   protected_data:
  145.  
  146.     // Reference to structure accompanying a notification requesting
  147.     // for the text of a particular tool.
  148.     //
  149.     TTooltipText& TipText;
  150. };
  151.  
  152. //
  153. // class TTooltip
  154. // ~~~~~ ~~~~~~~~
  155. // TTooltip encapsulates a tooltip window - i.e. a small popup window
  156. // that displays a single line of descriptive test giving the purpose
  157. // of the item underneath the current cursor location.
  158. //
  159. class _OWLCLASS TTooltip : public TControl {
  160.   public:
  161.     TTooltip(TWindow* parent, bool alwaysTip = true, TModule* module = 0);
  162.  
  163. #if defined(BI_PLAT_WIN32)
  164.     TTooltip(HWND hWnd, TModule* module = 0);
  165. #endif
  166.  
  167.    ~TTooltip();
  168.  
  169.     // Set state of tooltip
  170.     //
  171.     void        Activate(bool activate = true);
  172.  
  173.     // Add/remove/enumerate tools
  174.     //
  175.     bool        AddTool(const TToolInfo&);
  176.     void        DeleteTool(const TToolInfo&);
  177.     bool        EnumTools(uint index, TToolInfo&) const;
  178.  
  179.     // Update/retrive attribute of tools
  180.     //
  181.     bool        GetCurrentTool(TToolInfo&) const;
  182.     void        GetToolText(TToolInfo&) const;
  183.     uint        GetToolCount() const;
  184.     bool        GetToolInfo(TToolInfo&) const;
  185.     void        SetToolInfo(const TToolInfo&);
  186.     void        UpdateTipText(const TToolInfo&);
  187.  
  188.     bool        HitTest(TTooltipHitTestInfo&) const;
  189.     void        NewToolRect(const TToolInfo&);
  190.     void        RelayEvent(MSG&);
  191.     void        SetDelayTime(WPARAM flag, int delay);
  192.  
  193.   protected:
  194.     // Override TWindow virtual member functions
  195.     //
  196.     char far*   GetClassName();
  197.  
  198.   private:
  199.     // Hidden to prevent accidental copying or assignment
  200.     //
  201.     TTooltip(const TTooltip&);
  202.     TTooltip& operator =(const TTooltip&);
  203.  
  204.  
  205. #if defined(BI_PLAT_WIN16)
  206.   protected:
  207.     // Override virtual(s) from TWindow
  208.     //
  209.     void        GetWindowClass(WNDCLASS& wc);
  210.     void        SetupWindow();
  211.     void        CleanupWindow();
  212.     void        Paint(TDC& dc, bool erase, TRect& rect);
  213.  
  214.     // Routines implementing ObjectWindows Tooltips
  215.     //
  216.     void        Init();
  217.     void        Cleanup();
  218.     void        ShowActiveTip(TPoint& pt);
  219.     void        HideActiveTip();
  220.     void        EnableTimer();
  221.     void        DisableTimer();
  222.     void        RelayEvent(HWND receiver, uint msg, const TPoint& pt);
  223.  
  224.     // Message Response Functions
  225.     //
  226.     void        EvTimer(uint timerId);
  227.     HFONT       EvGetFont();
  228.     void        EvSetFont(HFONT hFont, bool redraw);
  229.     void        EvLButtonDown(uint modKeys, TPoint& point);
  230.     void        EvRButtonDown(uint modKeys, TPoint& point);
  231.  
  232.   private:
  233.     // Helpers used by OWL's implementation of TOOLTIPS
  234.     //
  235.     bool                Active;           // Flags if tooltip is active?
  236.     int                 Delay;            // Grace period before popping tip
  237.     TFont*              ToolFont;         // Font used by tooltip window
  238.     TToolInfo*          ActiveTool;       // Currently active tool
  239.     TToolInfo*          PotentialTool;    // Tool we're waiting on
  240.     TPoint              MouseLoc;         // Last recorded mouse loc
  241.     bool                TimerEnabled;     // Flags if Timer's currently set
  242.     TCollection<TToolInfo>* ToolList;     // Collection of Tools
  243.  
  244.   DECLARE_RESPONSE_TABLE(TTooltip);
  245. #endif  //  (BI_PLAT_WIN16)
  246. };
  247.  
  248. // Generic definitions/compiler options (eg. alignment) following the 
  249. // definition of classes
  250. #include <services/posclass.h>
  251.  
  252. #if defined(BI_NAMESPACE)
  253. } // namespace OWL
  254. #endif
  255.  
  256. //----------------------------------------------------------------------------
  257. // Inline implementation
  258. //
  259.  
  260. //
  261. // Sets the text of this tool by providing a string resource identifier
  262. // and the handle of the instance containing that resource.
  263. //
  264. inline void TToolInfo::SetText(int resId, HINSTANCE hinstance)
  265. {
  266.   lpszText = CONST_CAST(char far*, MAKEINTRESOURCE(resId));
  267.   hinst = hinstance;
  268. }
  269.  
  270. //
  271. // Sets the bounding rectangle of the tool. The coordinates are relative
  272. // to the upper-left corner of the client area of the window.
  273. // NOTE: This flag is only valid if the tool is a rectangle within
  274. //       the window and not a control parented to the window.
  275. //
  276. inline void TToolInfo::SetRect(const TRect& rc)
  277. {
  278.   rect = rc;
  279. }
  280.  
  281. //
  282. // If the IDs of two tools (or the Window Handles of two tools
  283. // for cases when 'uFlags & TTF_IDISHWND') are similar and the
  284. // handle of the window containing them matches, we'll infer that
  285. // the structures are referring to the same tool.
  286. //
  287. inline bool TToolInfo::operator==(const TToolInfo& ti) const
  288. {
  289.   return (uId == ti.uId && hwnd == ti.hwnd) ? true : false;
  290. }
  291.  
  292. //
  293. //
  294. //
  295. inline const char* 
  296. TToolInfo::GetCacheText() const 
  297. {
  298.   return (char*)(CONST_CAST(TToolInfo*, this)->CacheText);
  299. }
  300.  
  301. //
  302. //
  303. //
  304. inline void
  305. TToolInfo::FlushCacheText()
  306. {
  307.   CacheText = 0;
  308. }
  309.  
  310. //----------------------------------------------------------------------------
  311. // When ObjectWindows relies exclusively on the native implementation of
  312. // TOOLTIPS, the methods to manipulate the control are simple wrappers around
  313. // predefined TOOLTIP messages (TTM_xxxx).
  314. //
  315. #if defined(BI_PLAT_WIN32)
  316.  
  317. //
  318. // Activates or deactivates the tooltip control. If 'activate' is true,
  319. // the tooltip control is activated, If it is false the tooltip control
  320. // is deactivated.
  321. //
  322. inline void TTooltip::Activate(bool activate)
  323. {
  324.   SendMessage(TTM_ACTIVATE, TParam1(activate));
  325. }
  326.  
  327. //
  328. // Registers a tool with the tooltip control. The 'TToolInfo' parameter
  329. // contains information that the tooltip control needs to display text
  330. // for the tool.
  331. //
  332. inline bool TTooltip::AddTool(const TToolInfo& ti)
  333. {
  334.   return SendMessage(TTM_ADDTOOL, 0, TParam2(&ti)) != 0;
  335. }
  336.  
  337. //
  338. // Removes a tool from the tooltip control. You must invoke the
  339. // 'SetToolHandle' or 'SetToolId' method of TToolInfo to identify
  340. // the tool to remove. [i.e. the 'hwnd' or 'uId' members of the
  341. // TToolInfo must identify the tool].
  342. //
  343. inline void TTooltip::DeleteTool(const TToolInfo& ti)
  344. {
  345.   SendMessage(TTM_DELTOOL, 0, TParam2(&ti));
  346. }
  347.  
  348. //
  349. // Retrieves the information that the tooltip control maintains 
  350. // about the specified tool. Returns true if successul or false otherwise.
  351. // NOTE: The index is zero-based and the TToolInfo structure receives
  352. //       the information about the tool.
  353. //
  354. inline bool TTooltip::EnumTools(uint index, TToolInfo& ti) const
  355. {
  356.   return CONST_CAST(TTooltip*, this)->SendMessage(TTM_ENUMTOOLS,
  357.                                                   index, TParam2(&ti)) != 0;
  358. }
  359.  
  360. //
  361. // Retrieves information about the current tool. The 'TToolInfo'
  362. // parameter receives the information. Returns true if successful or
  363. // false otherwise.
  364. //
  365. inline bool TTooltip::GetCurrentTool(TToolInfo& ti) const
  366. {
  367.   return CONST_CAST(TTooltip*, this)->SendMessage(TTM_GETCURRENTTOOL,
  368.                                                   0, TParam2(&ti)) != 0;
  369. }
  370.  
  371. //
  372. // Retrieves the text associated with the specified tool. You must 
  373. // invoke the 'SetToolHandle' or 'SetToolId' method of TToolInfo to 
  374. // identify the tool. [i.e. the 'hwnd' or 'uId' members of the
  375. // TToolInfo must identify the tool].
  376. //
  377. inline void TTooltip::GetToolText(TToolInfo& ti) const
  378. {
  379.   CONST_CAST(TTooltip*, this)->SendMessage(TTM_GETTEXT, 0, TParam2(&ti));
  380. }
  381.  
  382. //
  383. // Returns the number of tools currently registered with the 
  384. // tooltip control. 
  385. //
  386. inline uint TTooltip::GetToolCount() const
  387. {
  388.   return (uint)CONST_CAST(TTooltip*, this)->SendMessage(TTM_GETTOOLCOUNT);
  389. }
  390.  
  391. //
  392. // Retrieves the information that the tooltip control maintains about
  393. // a tool. You must invoke the 'SetToolHandle' or 'SetToolId' method 
  394. // of TToolInfo to identify the tool. [i.e. the 'hwnd' or 'uId' members 
  395. // of the TToolInfo must identify the tool].
  396. //
  397. inline bool TTooltip::GetToolInfo(TToolInfo& ti) const
  398. {
  399.   return CONST_CAST(TTooltip*, this)->SendMessage(TTM_GETTOOLINFO, 0,
  400.                                                   TParam2(&ti)) != 0;
  401. }
  402.  
  403. //
  404. // Sets the information that the tooltip control maintains for a 
  405. // particular tool. You must invoke the 'SetToolHandle' or 
  406. // 'SetToolId' method of TToolInfo to identify the tool. 
  407. // [i.e. the 'hwnd' or 'uId' members of the TToolInfo must 
  408. // identify the tool].
  409. //
  410. inline void TTooltip::SetToolInfo(const TToolInfo& ti)
  411. {
  412.   SendMessage(TTM_SETTOOLINFO, 0, TParam2(&ti));
  413. }
  414.  
  415. //
  416. // Sets the text of a tool. You must invoke the 'SetToolHandle' or 
  417. // 'SetToolId' method of TToolInfo to identify the tool. 
  418. // [i.e. the 'hwnd' or 'uId' members of the TToolInfo must 
  419. // identify the tool]  
  420. //
  421. inline void TTooltip::UpdateTipText(const TToolInfo& ti)
  422. {
  423.   SendMessage(TTM_UPDATETIPTEXT, 0, TParam2(&ti));
  424. }
  425.  
  426. //
  427. // Determines whether a tool is within a specified point. The method
  428. // also retrieves information about the tool if one is identified at
  429. // that location. Returns true if a tool if found at the location or
  430. // false otherwise.
  431. //
  432. inline bool TTooltip::HitTest(TTooltipHitTestInfo& ttHTInfo) const
  433. {
  434.   return CONST_CAST(TTooltip*, this)->SendMessage(TTM_HITTEST, 0,
  435.                                                   TParam2(&ttHTInfo)) != 0;
  436. }
  437.  
  438. //
  439. // Updates the bounding rectangle of a tool. You must invoke the 'SetToolId' 
  440. // method of TToolInfo to identify the tool. [i.e. the 'uId' member
  441. // of the TToolInfo must identify the tool].
  442. //
  443. inline void TTooltip::NewToolRect(const TToolInfo& ti)
  444. {
  445.   SendMessage(TTM_NEWTOOLRECT, 0, TParam2(&ti));
  446. }
  447.  
  448. //
  449. // Passes a mouse message to the tooltip control for processing.
  450. //
  451. inline void TTooltip::RelayEvent(MSG& msg)
  452. {
  453.   SendMessage(TTM_RELAYEVENT, 0, TParam2(&msg));
  454. }
  455.  
  456. //
  457. // Sets the initial, reshow and autopopup durations for a tooltip
  458. // control. The 'flag' parameter can be one of the following:
  459. //      TTDT_AUTOMATIC: Automatically calculates the initial. reshow
  460. //                      and autopopup duration based on 'delay'.
  461. //      TTDT_AUTOPOP:   Sets the length of time before the tooltip
  462. //                      window is hidden if the cursor remains 
  463. //                      stationary in the tool's bounding rectangle
  464. //                      after the tooltip window has disappeared.
  465. //      TTDT_INITIAL:   Set the length of time that the cursor must
  466. //                      remain stationary within the bounding rectangle
  467. //                      before the tooltip window is displayed.
  468. //      TTDT_RESHOW:    Set the length of time before subsequent tooltip
  469. //                      windows are displayed when the cursor is moved
  470. //                      from one tool to another.
  471. //
  472. // NOTE: The 'delay' duration is in milliseconds.
  473. //
  474. inline void TTooltip::SetDelayTime(WPARAM flag, int delay)
  475. {
  476.   SendMessage(TTM_SETDELAYTIME, flag, TParam2(delay));
  477. }
  478.  
  479. #endif  // BI_PLAT_WIN32
  480. #endif  // OWL_TOOLTIP_H
  481.